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Abstract 

The  Velocity  Profile  Viewer  (VPV)  is  a  tool  for  visualiz¬ 
ing  time  series  of  velocity  profiles  developed  by  the  U.S.  Geo¬ 
logical  Survey  (USGS).  The  USGS  uses  VPV  to  preview  and 
present  measured  velocity  data  from  acoustic  Doppler  current 
profilers  and  simulated  velocity  data  from  three-dimensional 
estuarine,  river,  and  lake  hydrodynamic  models.  The  data  can 
be  viewed  as  an  animated  three-dimensional  profile  or  as  a 
stack  of  time-series  graphs  that  each  represents  a  location  in 
the  water  column. 

The  graphically  displayed  data  are  shown  at  each  time 
step  like  frames  of  animation.  The  animation  can  play  at  several 
different  speeds  or  can  be  suspended  on  one  frame.  The  viewing 
angle  and  time  can  be  manipulated  using  mouse  interaction.  A 
number  of  options  control  the  appearance  of  the  profile  and  the 
graphs.  VPV  cannot  edit  or  save  data,  but  it  can  create  a  Post¬ 
Script  file  showing  the  velocity  profile  in  three  dimensions.  This 
user  manual  describes  how  to  use  each  of  these  features.  VPV  is 
available  to  be  downloaded  for  free  from  the  World  Wide  Web 
at  http://ca.water.usgs.gov/pwgram/sfbay/vpv. 

Introduction 

The  Velocity  Profile  Viewer  (VPV)  is  a  software  appli¬ 
cation  developed  by  the  U.S.  Geological  Survey  (USGS)  for 
visualizing  scientific  data,  specifically  velocity  profiles.  It 
originally  was  created  in  response  to  evolving  data-collection 
and  three-dimensional  (3D)  modeling  technology  that  had  out¬ 
paced  older  visualization  methods.  Primarily,  it  was  designed 
to  meet  the  needs  of  a  group  of  research  scientists  studying  the 
San  Francisco  Bay  and  Delta,  but  it  has  evolved  into  a  tool  that 
other  scientists  can  use  to  study  environmental  flows. 

This  report  provides  a  formal  and  complete  descrip¬ 
tion  and  user  manual  for  VPV.  The  history  of  development  is 
given  to  provide  a  context  to  better  understand  the  software’s 
intended  uses  and  limitations.  Because  the  application’s  user 
interface  is  not  entirely  self-explanatory,  this  report  should  be 
a  valuable  resource  for  VPV  users,  making  it  faster  and  easier 
to  learn  important  features  and  use  them  effectively. 


VPV  is  available  on  the  World  Wide  Web  at  http:// 
ca.water.usgs.gov/program/sfbay/vpv/.  This  report  describes 
the  version  of  VPV  last  modified  on  August  15,  2004. 

Background 

Acoustic  Doppler  current  profiler  (ADVM)  measurement 
technology  was  developed  in  the  late  1970s  and  early  1980s  to 
remotely  measure  flow  velocities  of  discrete  layers  of  water  at 
multiple  locations  in  a  vertical  water  column.  When  data  from 
all  layers  are  grouped  at  an  instant  in  time,  they  form  a  veloc¬ 
ity  profile.  Prior  to  this  technology,  mechanical  current  meters 
were  the  primary  means  of  measuring  time  series  of  currents, 
but  they  only  could  collect  data  at  a  single  point.  Unfortu¬ 
nately,  deploying  mechanical  meters  in  certain  locations  is  not 
possible  and  it  is  not  practical  to  deploy  the  number  of  meters 
necessary  to  completely  cover  the  vertical  range  of  water  from 
bottom  to  surface. 

In  the  1980s,  ADVM  technology  for  deep-water  ocean 
environments  was  adapted  for  the  shallower  depths  of  inland 
waterways.  The  USGS  recognized  the  potential  of  ADVMs  for 
measurement  of  currents  in  rivers  and  estuaries  and  became 
interested  in  acquiring  and  testing  the  devices  (R.  Billings, 

U.S.  Geological  Survey,  written  commun.,  1985).  The  first 
USGS  deployment  of  an  upward-looking  ADVM  on  the 
bottom  of  a  body  of  water  was  in  1988  in  San  Francisco  Bay 
(Smith  and  others,  1991;  Burau  and  others,  1993).  Since  then, 
the  USGS  successfully  has  completed  many  such  deploy¬ 
ments  in  California  and  elsewhere  (Smith  and  others,  1995; 
Burau  and  others,  1998;  Gartner  and  Burau,  1999;  Cuetara  and 
others,  2001;  Simpson,  2001).  ADVMs  send  acoustic  signals 
to  record  the  speed  and  direction  of  water,  generally  at  fixed 
vertical  locations  in  a  water  column.  Each  vertical  location  is 
referred  to  as  a  bin,  evoking  the  image  of  drawers  stacked  in  a 
cabinet.  Upward-looking  ADVMs  generally  are  deployed  on 
a  platform  on  the  bottom  of  a  body  of  water  and  they  mea¬ 
sure  from  the  instrument  to  the  surface.  Downward-looking 
ADVMs  measure  from  the  surface  to  the  bottom  of  a  body 
of  water  and  commonly  are  mounted  on  a  boat.  Discussions 
in  this  report  generally  will  reflect  the  upward-looking  view 
point. 
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The  trend  of  increasing  ADVM  use  has  been  accompa¬ 
nied  by  a  similar  trend  of  applying  3D  hydrodynamic  models 
to  estuaries,  lakes,  and  rivers  (Cheng  and  Smith,  1990;  Smith 
and  Cheng,  1990;  Smith  and  Larock,  1993;  Smith,  1997). 
3D-model  simulations  can  generate  data  that  are  equivalent  to 
the  velocity  profiles  measured  by  ADVMs.  Regardless  of  the 
data’s  source,  visual  display  of  the  profiles  is  useful. 

Visualization 

Velocity  data  for  a  given  location  can  be  stored  as  speed 
and  direction  or  as  components  of  a  vector.  The  axial,  or  U, 
component  describes  the  speed  along  the  principal  direction 
of  flow.  The  transverse,  or  V,  component  describes  the  speed 
perpendicular  to  the  main  axis.  For  example,  if  the  principal 
direction  of  flow  is  along  an  east-west  axis,  then  the  trans¬ 
verse  component  would  be  along  a  north-south  axis.  The  third 
component,  which  is  aligned  with  the  vertical  axis,  is  typically 
ignored  because  of  its  relatively  small  magnitude. 

Each  ADVM  in  a  monitoring  network  records  a  time 
series  of  velocity  data  for  multiple  bins,  and  3D  computer 
models  can  generate  large  quantities  of  spatially  and  tem¬ 
porally  varying  velocity  data.  With  the  advancement  of  data 
collection  and  simulation  technology,  the  analysis  and  visual 
presentation  of  data  has  become  increasingly  challenging. 

One  way  to  present  velocity  data  is  to  graph  the  U  and  V 
components,  or  speed  and  direction,  versus  time  for  each  bin. 
This  is  simple  to  do  and  shows  a  complete  record  of  the  data, 
but  requires  significant  effort  to  interpret  and  compare  trends 
between  bins.  To  make  this  task  more  intuitive,  “stick  plots” 
that  show  each  vector  as  an  angled  line  occasionally  are  used. 
Unfortunately,  a  stack  of  stick  plots  presents  so  much  informa¬ 
tion  on  a  single  page  that  differences  between  bins  at  impor¬ 
tant  times  are  not  always  obvious  to  the  untrained  eye. 

It  is  most  intuitive  to  view  a  velocity  profile  as  a  3D 
drawing  in  space.  It  was  possible  in  the  late  1980s  to  develop 
software  to  create  static  figures  containing  a  single  velocity 
profile  in  3D  space  {fig.  7)  using  the  Computer  Associates 
Disspla  graphics  software  library.  The  data  in  each  bin  were 
shown  as  an  arrow  radiating  from  a  vertical  centerline  and 
a  projection  was  shown  below  the  profile  in  the  horizontal 
plane.  These  figures  were  used  for  analysis  and  in  publications 
(Burau  and  others,  1993). 

Although  these  static  figures  were  ideal  for  printed 
publications,  they  forced  the  choice  between  displaying  a 
simple  3D  profile  of  one  moment  in  time  or  displaying  a  more 


complete  record  of  data  in  a  series  of  graphs.  Ideally,  a  time 
series  of  3D  profiles  would  be  shown  in  succession,  so  a  large 
amount  of  data  could  be  presented  in  a  more  realistic  graphic 
form. 


The  Dop3d  Application 

In  the  early  1990s,  a  software  application  called  “dop3d” 
(fig.  2)  was  written  to  display  velocity  profile  animation  (J.R. 
Burau,  U.S.  Geological  Survey,  oral  commun.,  2002).  Dop3d 
displayed  velocity  profile  animation  using  a  3D  graphics 
library  called  the  IRIS  Graphics  Library  (IRIS  GL)  (Kilgard, 
accessed  luly  15,  2004),  which  ran  on  Silicon  Graphics,  Inc. 
(SGI)  workstations. 

The  dop3d  application  was  valuable  for  its  ability  to 
display  a  moving  picture  of  the  velocity  profile,  which  then 
could  be  used  to  preview  or  present  data.  Dop3ds  animated, 

3D  graphics  gave  even  casual  viewers  insight  into  the  hydro¬ 
dynamics  of  rivers  and  estuaries  that  otherwise  was  not  pos¬ 
sible.  By  the  mid  1990s,  dop3d,  or  a  similar  application,  was 
in  demand  for  use  on  the  more  popular  Microsoft  Windows 
platform.  Unfortunately,  IRIS  GL  was  not  available  outside  of 
SGI  computers;  therefore,  dop3d  was  not  easily  portable. 

The  Velocity  Application 

In  1997,  this  author  began  developing  “velocity,”  an 
application  written  in  the  C  language  (Kernighan  and  Ritchie, 
1988)  and  using  the  Open  Graphics  Library  (OpenGL) 
(OpenGL.org,  accessed  July  15,  2004),  the  open-platform 
successor  to  IRIS  GL.  OpenGL  provides  functions  for  drawing 
graphics,  not  for  mouse  and  keyboard  input.  More  powerful 
user-interface  libraries  such  as  Microsoft  Loundation  Classes 
(MLC)  (Jones,  1999)  were  rejected  in  favor  of  the  more 
portable  Graphics  Library  Utility  Toolkit  (GLUT)  (OpenGL. 
org,  accessed  July  15,  2004),  which  provides  a  very  basic  user 
interface,  but  allows  the  application’s  source  code  to  be  com¬ 
piled  without  change  for  Windows,  Unix,  or  other  platforms. 

In  anticipation  of  wide  distribution,  “velocity”  also  was 
designed  to  be  user-friendly.  Commands  could  be  chosen  from 
a  popup  menu,  and  the  animation  and  profile  appearance  could 
be  controlled  using  the  mouse  or  keyboard.  By  1998,  “veloc¬ 
ity”  nearly  was  implemented  completely  and  renamed  “Velocity 
Profde  Viewer”  (“VPV”). 
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Figure  1.  Example  showing  a  velocity  profile  illustration  created  using  the  Computer 
Associates  Disspla  graphics  software  library  (Burau  and  others,  1993). 


Figure  2.  Velocity  profile  displayed  by  the  dop3d  application. 
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The  Velocity  Profile  Viewer 
Application 

Initially  used  by  USGS  research  scientists  studying  the 
San  Francisco  Bay  and  Delta,  VPV  now  is  used  by  other 
USGS  scientists,  cooperating  agencies,  and  engineers  in 
private  industry.  Versions  of  VPV  have  been  compiled  for 
Windows  and  SGI  IRIX  platforms,  and  VPV  can  be  compiled 
for  other  platforms  that  support  C,  OpenGL,  and  GLUT. 

VPV  reads  the  same  data  format  that  was  developed 
within  USGS  for  dop3d  and  other  ADVM  post-processing 
applications,  and  is  described  in  appendix  2  of  this  report.  VPV 
provides  more  features  than  dop3d,  such  as  graphs  of  the  U 
and  V  component  values  for  each  bin,  a  variety  of  displays  for 
the  profile,  and  PostScript  (Adobe  Systems,  Inc.,  1985,  1990) 
output.  However,  VPV  is  a  viewer  only;  it  has  no  editing  or 
data-saving  capability.  VPV  opens  a  single  data  file,  displays  a 
single  velocity  profile,  and  animates  that  profile  (fig .  3). 

By  default,  VPV  shows  a  3D  Profile  View,  which  can 
be  switched  to  a  Bin  Graph  View  using  a  mouse  or  keyboard 
command.  The  velocity  profile  is  time-oriented  and  always 
corresponds  exactly  to  one  date  and  time.  The  animated  profile 
is  shown  with  arrows  or  a  shaded  surface  to  represent  the  U 
and  V  velocity  vectors.  The  animation  can  be  viewed  interac¬ 
tively  from  any  angle,  paused,  advanced  by  frame,  or  played  at 
several  different  speeds. 


Once  a  file  is  loaded  successfully,  the  data  for  the  first 
time  step  are  displayed  in  the  3D  Profile  View.  Instructions 
for  installing  and  running  VPV  are  given  in  appendix  1.  VPV 
immediately  shows  the  profile  for  each  successive  time,  thus 
creating  the  illusion  of  animation.  Once  the  animation  begins, 
the  user  can  pause  the  animation,  switch  to  the  Bin  Graph 
View,  or  execute  other  commands.  Minimizing  the  application 
prevents  its  playing  forward  or  using  any  processor  resources. 

When  the  viewer  advances,  the  Time  and  Time  Step 
Number  labels  change,  the  three-dimensional  profile  is 
updated,  and  the  Main  Graph  scrolls  so  that  the  point  on 
its  time  axis  that  represents  the  present  time  step  intersects 
the  Time  Marker  Line.  Figure  4A-D  shows  four  sequential 
screen  captures  of  VPV  animation.  The  time  required  to  play 
the  sequence  ranges  from  a  fraction  of  one  second  to  several 
seconds  depending  on  the  Time  Step  Increment  and  the  speed 
of  the  computer.  In  figure  4  A,  the  U  components  of  the  vectors 
range  from  slightly  negative  at  the  bottom  of  the  profile  to 
greatly  negative  at  the  top.  In  figure  4B,  the  U  components  of 
the  vectors  have  become  smaller  in  magnitude,  although  still 
negative.  In  figure  4C,  the  U  components  of  the  vectors  are 
slightly  positive  at  the  bottom  of  the  profile,  while  those  at  the 
top  are  slightly  negative.  In  figure  4D,  the  U  components  of 
the  vectors  range  from  slightly  positive  at  the  bottom  of  the 
profile  to  greatly  positive  at  the  top. 


Figure  3.  A  three-dimensional  profile  displayed  by  the  Velocity  Profile  Viewer. 
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Figure  4.  Four  sequential  frames  of  a  sample  profile  animation  displayed  by  the  Velocity  Profile  Viewer. 

Each  frame  shown  is  for  June  8, 1995.  (A)  Time  step  1024  representing  data  at  14:10;  (B)  time  step  1038  representing  data  at 
16:30;  (C)  time  step  1042  representing  data  at  17:10;  and  (D)  time  step  1054  representing  data  at  19:10. 


Application  Layout 

VPV  appears  in  a  single  window  that  can  be  toggled 
between  a  3D  Profile  View  and  a  Bin  Graph  View.  Compo¬ 
nents  of  the  3D  Profile  View  are  shown  and  labeled  in  figure  5. 
Components  of  the  Bin  Graph  View  are  shown  and  labeled  in 
figure  6.  The  window  does  not  contain  a  menu  bar  or  use  dia¬ 
log  boxes.  The  user  interacts  with  the  program  by  clicking  and 
dragging  the  mouse,  choosing  commands  from  a  popup  menu 
(fig.  7),  or  by  typing  on  the  keyboard.  For  details,  refer  to  the 
“Mouse  and  Keyboard  Control”  section  of  this  report. 


Most  components  of  the  3D  Profile  View  have  fixed  loca¬ 
tions.  The  components  fall  into  three  categories:  text  informa¬ 
tion,  3D  objects,  and  time-series  graphs.  The  location  of  text 
information  appears  unchanged  in  the  3D  Profile  View  and 
the  Bin  Graph  View.  3D  objects  appear  only  in  the  3D  Profile 
View  and  include  the  velocity  profile,  grid,  and  axis.  The 
Main  Graph,  which  contains  time-series  curves  of  water-level 
and  bin-averaged  U  velocity,  appears  in  both  views.  The  four 
graphs  of  individual  bins  appear  only  in  the  Bin  Graph  View. 

The  window  can  be  resized  by  positioning  the  mouse 
pointer  on  the  window  border  and  dragging  it  to  the  desired 
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Figure  5.  Components  of  the  Three-Dimensional  Profile  View  displayed  by  the  Velocity  Profile  Viewer. 


size.  The  contents  of  the  window  adjust  to  fit  the  new  size; 
however,  if  the  window  is  much  wider  than  its  height,  or  much 
higher  than  its  width,  the  display  will  be  distorted.  Figure  8 
shows  four  different  sized  VPV  windows  displaying  the  same 
content,  and  shows  resulting  distortion. 

To  provide  flexibility  and  to  account  for  varying  user 
preferences,  VPV  can  show  lines  and  text  in  thicknesses  rang¬ 
ing  from  one  to  six  pixels.  When  the  VPV  window  is  small, 
thin  lines  and  text  provide  the  necessary  detail  to  resolve  all 
the  components.  When  the  overall  size  of  the  window  is  large, 
such  as  would  be  used  on  a  high-resolution  monitor,  the  thin 
lines  and  text  can  become  difficult  to  see.  For  more  informa¬ 
tion  on  adjusting  line  thickness,  see  “View  Commands”  under 
the  “Mouse  and  Keyboard  Control”  section  of  this  report. 

Text  Information 

Two  lines  of  yellow  text  are  at  the  top  corners  of  the  VPV 
window  (fig.  5).  The  top  left  line  displays  the  date  and  time 
of  the  measured  or  simulated  data  being  shown  in  the  veloc¬ 


ity  profile.  The  date  and  time  advance  with  the  animation. 
Immediately  below  this  line  is  the  label  “Velocity  in  cm/s,” 
which  indicates  that  centimeters  per  second  are  the  units  of  the 
data  displayed.  The  software  cannot  display  an  alternate  units 
of  measure  label,  but  the  label  can  be  hidden  if  it  is  inappro¬ 
priate  for  the  data  being  viewed.  The  top  right  line  displays  a 
description  of  the  location,  as  read  from  the  data  file  header. 
This  field  does  not  change  once  the  data  file  has  been  read. 
Immediately  below  this  line  is  the  principal  direction  of  the  U 
component.  When  the  application  starts,  this  value  is  “None”, 
but  if  the  user  chooses  a  new  angle,  the  angle  is  shown  in 
degrees,  clockwise,  from  north.  For  more  information  on  the 
principal  direction,  see  “Orientation  Commands”  under  the 
“Mouse  and  Keyboard  Control”  section  of  this  report. 

The  yellow  text  in  the  bottom  left  corner  of  the  VPV 
window  displays  the  rate  at  which  the  animation  is  playing. 
The  yellow  text  in  the  bottom  right  corner  shows  the  present 
time  step  and  the  total  number  of  time  steps.  Note  that  the 
actual  colors  that  appear  onscreen  may  vary  depending  on  the 
settings  for  the  monitor,  display  driver,  or  operating  system 
color  mode. 
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Figure  6.  Components  of  the  Bin  Graph  View  displayed  by  the  Velocity  Profile  Viewer. 
The  Main  Graph  information  labels  are  the  same  as  the  Three-Dimensional  Profile  View. 
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Figure  7.  Popup  menu  showing  the  Animation  submenu  displayed  by  the  Velocity  Profile  Viewer. 
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Figure  8.  Four  different  sized  Velocity  Profile  Viewer  windows  displaying  the  same  content. 

The  content  always  fills  the  window  area,  regardless  of  distortion.  The  windows  are  (A)  relatively  large  (1 184  x  855 
pixels);  (B)  stretched  vertically  (415  x  855  pixels);  (C)  stretched  horizontally  (1 184  x  305  pixels);  and  (D)  relatively 
small  (415  x  305  pixels). 


The  Main  Graph 

The  Main  Graph  shows  the  mean  U  value  of  all  the 
bins  versus  time  (fig.  5).  The  mean  value  line  in  the  graph  is 
magenta  and  is  labeled  as  Bin-Averaged  U.  The  vertical  scale 
is  indicated  by  magenta  axis  labels  at  the  two  right  corners  of 
the  graph.  The  horizontal  scale  is  not  indicated,  but  the  value 
where  the  graph  intersects  the  Time  Marker  Line  is  always 
written  in  the  date  and  time  labels.  The  mean  of  the  bin-aver¬ 
aged  U  velocity  over  all  the  time  values  is  a  magenta  horizon¬ 
tal  dotted  line. 

When  water-level  data  are  provided  in  the  input  file,  they 
are  shown  as  a  cyan  line  in  the  Main  Graph  with  no  assump¬ 
tions  made  regarding  units  or  datum.  The  axis  label  and  title 
on  the  left  edge  of  the  graph  also  are  cyan,  and  the  mean  of  the 
water-level  curve  is  a  cyan  horizontal  dotted  line. 

Three-Dimensional  Profile  View 

The  3D  Profile  View  is  the  standard  view  in  VPV  and 
shows  the  data  as  a  3D  velocity  profile  (fig.  5)  with  the  Main 
Graph  at  the  top  and  descriptive  yellow  text  in  each  corner  of 
the  window.  The  3D  velocity  profile  displays  a  red,  vertical 
line  with  arrows  radiating  perpendicularly  to  it  at  regularly 


spaced  vertical  intervals.  Each  arrow  consists  of  a  shaft  with  a 
flat,  vertically  aligned  yellow-green  arrowhead.  The  size  of  the 
arrowhead  fluctuates  with  the  length  of  the  shaft.  Depending 
on  user  preference,  all  arrow  shafts  may  be  red,  or  they  may 
vary  from  yellow  at  the  top  to  red  at  the  bottom. 

A  green  line  connects  the  arrow  tips  of  all  the  bins 
defined  in  the  data  file.  If  a  bin  has  a  velocity  of  zero  for  a 
given  time  step,  the  arrow  tip  and  the  green  line  are  located  on 
top  of  the  center  line.  This  can  be  seen  when  displaying  data 
sets  in  which  tidal  variation  causes  the  water  surface  to  drop 
below  the  top  bin.  The  effect  is  a  green  outline  that  stretches 
from  the  top  of  the  highest  nonzero  arrow  back  to  the  center 
line  at  the  bin  above  it.  If  all  the  bins  have  a  velocity  of  zero, 
the  centerline  will  appear  green  where  it  is  covered  by  the 
green  outline. 

The  profile  base  consists  of  a  flat,  blue  rectangle  in  the 
U-V  plane  and  an  optional  grid  with  tick  marks  that  can  be 
shown  on  the  rectangle.  Axis  labels  are  shown  along  the  bot¬ 
tom  and  left  side  of  the  grid  area.  The  vertical  space  interval 
between  the  profile  base  and  the  lowest  arrow  is  equal  to  the 
space  between  the  other  arrows. 

An  optional  velocity  projection  is  shown  on  the  base  to 
show  the  spread  of  vectors  in  the  U-V  plane.  This  causes  the 
profile  arrows  and  surface  to  be  shown  with  a  height- variable 
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color  scheme  that  fades  from  yellow  at  the  top  to  red  at  the 
bottom.  The  color  of  each  projected  line  matches  the  color  of 
the  line  directly  above  it  on  the  profile,  thus  allowing  the  user 
to  determine  the  bin  represented  by  each  projected  line. 

A  shaded  surface  also  may  be  shown  on  the  profile  to  give 
it  the  appearance  of  a  flag  flying  from  a  pole.  The  surface  is 
shaded  blue  and  illuminated  by  a  virtual  light  to  reveal  its  shape. 

Bin  Graph  View 

The  Bin  Graph  View  displays  the  velocity  data  in  four  ver¬ 
tically  stacked  graphs  below  the  Main  Graph  (fig.  6).  By  default, 
each  graph  displays  a  different  bin,  with  the  bottom  graph 
showing  data  from  the  first  bin,  and  the  top  graph  showing  data 
from  the  last  bin.  The  two  middle  graphs  show  data  from  bins 
at  roughly  equally  spaced  intervals  in  the  middle  of  the  profile. 
The  arrangement  can  be  changed  from  the  default  so  that  any 
graph  displays  data  for  any  bin  using  the  Bin  Graphs/Increase 
and  Bin  Graphs/Decrease  commands,  which  are  described  in  the 
“Bin  Graphs  Commands”  sub  section  in  the  “Mouse  and  Key¬ 
board  Control”  section  of  this  report.  The  bin  number  is  shown 
to  the  right  of  each  graph  in  the  same  color,  varying  from  yellow 
to  red,  as  the  bin’s  arrow  in  the  3D  profile. 


The  horizontal  scale  is  the  same  as  for  the  Main  Graph 
at  the  top  of  the  window.  The  vertical  scale  is  the  same  for  all 
bins  shown  so  that  relative  magnitude  can  be  determined.  The 
limits  are  rounded  to  the  nearest  increment  of  5,  10,  25,  or  one 
of  those  numbers  multiplied  by  a  power  of  10.  The  minimum 
and  maximum  values  of  each  vertical  axis  are  shown  near  the 
right  corners  of  each  of  the  four  graphs. 

By  default,  the  Bin  Graph  View  shows  stick  plots  of  bins, 
which  represent  the  vector  at  each  time  step  as  an  angled  line 
(figs.  9A-C).  The  height  of  the  line  represents  the  U  compo¬ 
nent,  and  the  horizontal  offset  of  the  endpoint  represents  the  V 
component.  “Sticks”  with  positive  V  values  angle  to  the  left, 
whereas  those  with  negative  V  values  angle  to  the  right.  The 
V  scale  for  sticks  is  dependent  on  the  time  span  shown  within 
the  graph,  so  it  is  not  the  same  as  the  U  scale.  The  sticks  may 
appear  to  be  extremely  skewed  if  the  principal  direction  has 
not  been  set  correctly  (fig.  9B).  For  information  about  the  prin¬ 
cipal  direction,  see  the  “Orientation  Commands”  section  in  the 
“Mouse  and  Keyboard  Control”  section  of  this  report.  If  the 
time  span  is  expanded,  some  sticks  will  be  omitted  to  avoid 
overcrowding  in  the  graph  (fig.  9C). 

The  U  and  V  components  can  be  shown  as  separate 
curves  on  the  bin  graphs.  The  U  curve  is  shown  in  magenta 


Figure  9.  Three  different  displays  of  the  same  bin  from  the  Bin  Graph  View  in  the  Velocity  Profile  Viewer. 
The  sticks  are  (A)  easy  to  discern;  (B)  skewed  because  the  principal  direction  is  not  set;  (C)  sparse  because 
the  time  span  has  been  expanded. 
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and  the  V  curve  is  shown  in  cyan  (fig.  6).  When  the  principal 
direction  is  properly  aligned,  the  V  curve  is  minimized  and  the 
U  curve  is  maximized  (fig.  9A). 

Whether  showing  sticks  or  component  curves,  each  bin 
graph  always  has  a  green,  dotted  horizontal  line.  Rather  than 
representing  the  mean,  as  do  the  dotted  lines  on  the  Main 
Graph,  this  green  dotted  line  represents  zero  on  the  vertical 
axis.  For  further  information  on  bin  graph  properties,  see  the 
“Bin  Graphs  Commands”  sub  section  in  the  “Mouse  and  Key¬ 
board  Control”  section  of  this  report. 


Mouse  Control  in  the  Main  Graph 

If  the  left  mouse  button  is  pressed  when  the  cursor  is 
within  the  Main  Graph,  the  present  time  step  will  change  as 
the  mouse  is  dragged.  Dragging  the  mouse  to  the  left  pans 
the  graph  to  the  left  and  advances  the  time  step.  Dragging  the 
mouse  to  the  right  pans  the  graph  to  the  right  and  moves  the 
time  step  backward  (see  “ vpv_timedrag.avi ”  video).  Holding 
down  the  Ctrl+Alt  keys  will  force  this  behavior,  even  if  the 
cursor  is  outside  the  Main  Graph. 


Mouse  and  Keyboard  Control 

Left  Mouse  Button  Control 

Much  of  the  user  interaction  with  VPV  involves  “drag¬ 
ging”  the  mouse,  which  is  defined  as  holding  down  the  left 
mouse  button  while  moving  the  mouse.  The  application’s 
response  depends  on  which,  if  any,  meta-keys  are  held  down 
on  the  keyboard  while  dragging  the  mouse. 

Mouse  Control  in  the  Three-Dimensional  Profile 
View 

If  no  keys  are  held  down,  and  the  mouse  pointer  is  not 
on  the  Main  Graph  when  the  left  mouse  button  is  pressed, 
the  profile  will  rotate  in  tandem  with  the  movements  of  the 
mouse.  This  allows  the  profile  to  be  viewed  from  any  angle  (fig. 
70A-D).  The  rotation  works  in  a  similar  way  to  a  trackball  input 
device  where  the  directional  movement  of  one’s  hand  causes 
the  rotation  of  the  ball.  In  VPV,  clicking  on  the  left  side  of  the 
profile  and  dragging  the  mouse  to  the  right  will  rotate  the  left 
side  of  the  profile  around  to  the  front.  Clicking  at  the  top  of 
the  profile  and  dragging  the  mouse  down  will  rotate  the  top  of 
the  profile  down  to  show  the  top  view.  (See  “ vpv_rotation.avi ” 
video) 

Holding  down  the  Alt  key  while  dragging  the  mouse 
vertically  will  scale  the  profile  larger  or  smaller.  Holding 
down  the  Shift  key  while  dragging  the  mouse  vertically  will 
reposition  the  profile  vertically.  Holding  down  the  Ctrl  key 
while  dragging  the  mouse  in  the  3D  Profile  View  will  cause 
the  profile  to  continue  rotating  even  after  the  mouse  button  is 
released.  The  rotation  speed  and  direction  are  determined  by 
the  speed  and  direction  in  which  the  mouse  was  dragged. 


VPV  Rotation  Video. 


Mouse  Control  in  the  Bin  Graph  View 

When  in  the  Bin  Graph  View,  dragging  the  mouse  left 
and  right  causes  the  graphs  to  pan  and  the  present  time  step  to 
be  moved  forward  or  back,  just  as  it  does  on  the  Main  Graph 
in  the  3D  Profile  View.  This  behavior  happens  in  the  Bin 
Graph  View  no  matter  where  the  cursor  is  placed  when  the  left 
mouse  button  is  clicked. 

Holding  down  the  Alt  key  while  dragging  the  mouse 
vertically  changes  the  scale  of  the  y-axes.  Holding  down  the 
Shift  key  while  dragging  the  mouse  vertically  translates  all  the 
graphs  along  their  y-axes.  Whether  scaling  or  shifting,  each 
vertical  axis  label  advances  to  the  nearest  round  number.  The 
Bin- Averaged  U  graph  also  translates,  although  its  axis  limits 
are  not  rounded. 

Right  Mouse  Button  Commands 

Clicking  the  right  mouse  button  when  the  cursor  is 
anywhere  in  the  VPV  window  causes  a  popup  menu  to  appear 
next  to  the  mouse  pointer  (fig.  11).  On  the  Windows  operating 
system,  the  animation  freezes  when  the  popup  menu  is  dis¬ 
played,  whereas  on  Unix,  the  animation  continues.  The  menu 
contains  the  following  submenus:  Jump,  Zoom,  View,  Axis, 
Time  Series,  Orientation,  Animation,  Bin  Graphs,  and  Help. 

Commands  are  shown  on  each  submenu  and  at  the 
bottom  of  the  main  menu.  The  user  can  execute  the  desired 
command  by  selecting  it  with  the  mouse.  Since  frequently 
used  commands  are  practical  only  when  using  the  keyboard, 
the  popup  menu  often  is  most  useful  as  a  reference  to  help 
remember  the  command-key  associations.  The  commands  are 
described  in  the  “Keyboard  Commands”  section  of  this  report. 


VPV  Timedrag  Video. 


Mouse  and  Keyboard  Control 


Figure  10.  Four  views  of  the  same  velocity  profile  in  the  Velocity  Profile  Viewer  from  different  angles. 

The  profile  viewing  angle  is  from  (A)  the  front,  looking  straight  across;  (B)  the  front,  left  side,  looking  slightly  down¬ 
ward;  (C)  the  front,  right  side,  looking  sharply  downward;  and  (D)  the  right  side,  looking  slightly  upward. 
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Figure  11.  The  Velocity  Profile  Viewer  as  it  looks  after  clicking  the  right  mouse  button  anywhere  in  the  window. 
A  popup  menu  appears  next  to  the  mouse  pointer. 
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Keyboard  Commands 

All  popup  menu  commands  are  available  as  keyboard 
shortcuts,  with  the  corresponding  key  shown  in  parenthe¬ 
ses  next  to  each  command  on  the  menu.  The  user  can  find 
the  desired  command  key  by  looking  on  the  menu  and  later 
execute  the  command  by  typing  that  key.  The  following 
subsections  correspond  to  submenus  on  the  popup  menu.  The 
commands  work  identically,  regardless  of  whether  they  are 
issued  using  the  keyboard  or  the  mouse. 

Jump  Commands 

Jump  commands  are  used  to  look  at  a  different  part  of 
the  time  series.  The  commands  can  be  given  while  animation 
is  running  or  stopped.  Table  1  describes  the  commands  on  the 
Jump  menu. 

Zoom  Commands 

Zoom  commands  differ  from  scaling  using  the  mouse  and 
Alt  key.  Scaling  with  the  mouse  changes  the  size  of  the  profile, 
as  well  as  the  3D  axis  labels  and  titles.  Scaling  with  the  zoom 
commands  changes  only  the  size  of  the  profile.  These  com¬ 
mands  are  useful  when  the  3D  axis  labels  are  the  correct  size 
but  the  profile  is  too  large  or  small.  When  viewing  the  bin 
graphs,  these  commands  change  the  limits  of  the  y-axes.  Table 
2  describes  the  commands  on  the  Zoom  menu.  Figures  12  and 
13  show  the  effects  of  zooming  out  and  in,  respectively. 


Table  1.  Commands  on  the  Jump  menu  of  the  Velocity  Profile 
Viewer. 


Command  Key 

Command  Description 

0 (zero) 

Jumps  to  the  beginning  of  the  time  series. 

F 

Jumps  forward  1  time  step.  This  can  be  used 
to  manually  advance  the  time  step  when  the 
animation  is  stopped. 

Shift+F 

Jumps  forward  10  time  steps. 

H 

Jumps  forward  100  time  steps. 

T 

Jumps  forward  1,000  time  steps. 

B 

Jumps  backward  1  time  step. 

Shift+B 

Jumps  backward  10  time  steps. 

Shift+H 

Jumps  backward  100  time  steps. 

Shift+T 

Jumps  backward  1,000  time  steps. 

Table  2.  Commands  on  the  Zoom  menu  of  the  Velocity  Profile 
Viewer. 

[See  figures  12-13  for  examples] 

Command  Key 

Command  Description 

I 

In  the  3D  Profile  View,  moves  the  viewpoint  slightly 
closer  to  the  profile. 

In  the  Bin  Graph  View,  shows  a  slightly  smaller 
span  on  the  Y  axis. 

Shift+I 

In  the  3D  Profile  View,  moves  the  viewpoint  much 
closer  to  the  profile. 

In  the  Bin  Graph  View,  shows  a  much  smaller  span 
on  the  Y  axis. 

O 

In  the  3D  Profile  View,  moves  the  viewpoint  slightly 
farther  from  the  profile. 

In  the  Bin  Graph  View,  shows  a  slightly  larger  span 
on  the  Y  axis. 

Shift+O 

In  the  3D  Profile  View,  moves  the  viewpoint  much 
farther  from  the  profile. 

In  the  Bin  Graph  View,  shows  a  much  larger  span 
on  the  Y  axis. 
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Figure  12.  The  Three-Dimensional  Profile  View  of  the  Velocity  Profile  Viewer  after  zooming  out  far  from  the  profile. 
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Figure  13.  The  Three-Dimensional  Profile  View  of  the  Velocity  Profile  Viewer  after  zooming  in  close  to  the  profile. 
This  view  shows  that  any  portion  of  the  profile  that  encroaches  on  the  Main  Graph  area  is  blocked  from  view. 
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View  Commands 

View  commands  control  the  appearance  of  the  profile 
and  the  presentation  of  text  information.  Table  3  describes  the 
commands  on  the  View  menu.  Figures  14  and  15  show  the 
effects  of  the  View  Menu  commands  “S”,  “A”,  and  “C”  (table 
3)  on  the  3D  profile,  which  toggle  a  smooth-shaded  surface, 
vector  arrows,  and  the  color  projection,  respectively.  Figure  16 


shows  the  effects  of  the  View  commands  “G”,  “1”,  “2”,  “3”, 
and  “4”  on  the  profile  base  and  text  information,  which  toggle 
the  first,  second,  and  bottom  lines  of  text,  axis  labels  and 
titles,  and  an  axis  grid  (table  3),  respectively.  Figure  1 7  shows 
the  effect  of  the  Julian  date  command,  command  “J”,  which 
toggles  the  format  of  the  date  label  between  standard  month/ 
day  and  Julian  day. 


Table  3.  Commands  on  the  View  menu  of  the  Velocity  Profile  Viewer. 

[Most  of  these  commands  act  as  toggles;  issuing  the  command  a  second  time  will  restore  the  original  state.  When  changing  text  and  line  width,  issuing  the  com¬ 
mand  six  times  will  cycle  back  to  the  original  state.  See  figures  14-24  for  examples] 


Command 

Key 


Command  Description 


Shows  the  3D  profile  with  a  lit,  smooth-shaded  surface 
(shown  in  figs.  14-15). 

Shows  the  3D  profile  with  vector  arrows  (shown  in/zgi. 
14-15). 

In  the  3D  Profile  View,  makes  the  arrow  or  surface 
segment  for  each  bin  a  different  color.  Projects  the 
colors  onto  the  profile  base  to  show  the  relative  speed 
and  direction  in  the  horizontal  plane  (shown  in  figs. 
14-15). 

In  the  Bin  Graph  View,  draws  a  blue-to-black  fade  for 
the  background  for  easier  distinction  between  graphs. 
Improves  appearance  at  the  expense  of  frame  rate 
(shown  in/zg.s.  34-35). 

Uses  anti-aliasing  to  make  lines  and  text  smoother  and 
less  jagged.  Antialiasing  reduces  sharpness,  but 
generally  improves  the  appearance  of  diagonal  lines. 
Thin  lines  and  text  may  look  blurry.  Appearance  and 
performance  vary  depending  on  hardware  configura¬ 
tions  (shown  in  figs.  23-24). 

Shows  the  first  line  of  text  information  including  date, 
time,  and  location  labels,  (shown  in  fig.  16). 

Shows  the  second  line  of  text  including  the  units  and 
principal  direction  labels  (shown  in  fig.  16). 

Shows  the  bottom  line  of  text  including  the  time-step 
increment  and  time  step  labels  (shown  in  fig.  16). 


Command 

Key 

Command  Description 

4 

Shows  axis  labels  and  titles  on  the  3D  profile  and  time- 
series  graphs  (shown  in  fig.  16). 

G 

In  the  3D  Profile  View,  shows  a  grid  on  the  base  of  the 
3D  profile  (shown  in  fig.  17). 

J 

Shows  the  date  in  Julian  format  rather  than  the  usual 
month/day/year  format. 

R 

In  the  3D  Profile  View,  resets  the  profile’s  position, 
rotation,  scale,  and  zoom  to  their  original  values. 

In  the  Bin  Graph  View,  resets  the  zoom  and  vertical 
translation. 

U 

Makes  the  window  full  screen  and  hides  the  window 

title  bar  and  borders. 

Shift+1 

Increases  the  thickness  of  small  text  by  one  pixel.  Once 
the  thickness  reaches  six  pixels,  it  cycles  back  to  one 
pixel  (see  figs.  18-24). 

Shift+2 

Increases  the  thickness  of  large  text  by  one  pixel.  Once 
the  thickness  reaches  six  pixels,  it  cycles  back  to  one 
pixel  (see  figs.  18-24). 

Shift+3 

Increases  the  thickness  of  thin  lines  by  one  pixel.  Once 
the  thickness  reaches  six  pixels,  it  cycles  back  to  one 
pixel  (see  figs.  18-24). 

Shift+4 

Increases  the  thickness  of  wide  lines  by  one  pixel. 

Once  the  thickness  reaches  six  pixels,  it  cycles  back 
to  one  pixel  (see  figs.  18-24). 
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Figure  14.  Four  different  displays  of  the  Three-Dimensional  Profile  View  of  the  Velocity  Profile  Viewer  with  the  color 
projection  turned  off. 

(A)  arrows  and  surface  turned  off;  (B)  arrows  turned  on  and  surface  turned  off;  (C)  arrows  turned  off  and  surface  turned 
on;  and  (D)  arrows  and  surface  turned  on. 


VPV — The  Velocity  Profile  Viewer  User  Manual 


Figure  15.  Four  different  displays  of  the  Three-Dimensional  Profile  View  of  the  Velocity  Profile  Viewer  with  the  color 
projection  turned  on. 

(A)  Arrows  and  surface  turned  off;  (B)  arrows  turned  on  and  surface  turned  off;  (C)  arrows  turned  off  and  surface  turned 
on;  and  (D)  arrows  and  surface  turned  on. 
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Figure  16.  Screen  captures  of  the  Velocity  Profile  Viewer  showing  variations  of  the  Three-Dimensional  Profile  View  components. 
(A)  devoid  of  text 
second  lin 

step;  and  (F)  with  axis  labels  next  to  the  three-dimensional  profile  grid  and  the  Main  Graph. 
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The  View  menu  also  has  commands  for  controlling  the 
line  weight  of  small  text  such  as  the  axis  labels  (Shift+1, 
table  3),  large  text  such  as  the  date  and  location  (Shift+2, 
table  3),  narrow  lines  such  as  the  curves  on  graphs  (Shift+3, 
table  3)  and  wide  lines  such  as  the  3D  profile’s  arrow  lines 
(Shift+4,  table  3).  Possible  combinations  include,  but  are  not 
limited  to,  a  large-sized  window  and  wide  line  weight  (fig. 
18),  a  medium-sized  window  and  wide  line  weight  (fig .  19), 


a  medium-sized  window  and  medium  line  weight  (fig.  20),  a 
medium-sized  window  and  narrow  line  weight  (fig.  21),  and 
a  small-sized  window  and  narrow  line  weight  (fig.  22).  Each 
time  a  command  to  change  line  weight  thickness  is  given,  the 
width  is  increased  by  one  pixel.  Once  the  thickness  reaches 
six  pixels,  giving  the  command  sets  the  thickness  back  to  one 
pixel.  Figures  23  and  24  show,  in  detail,  the  effects  of  the  com¬ 
mands  for  controlling  antialiasing  and  line  and  text  thickness. 


10^0^9^510 


Figure  17.  Screen  captures  of  the  date  "June  2, 1995,  at  3:10  p.m."  in  (A)  standard  and  (B)  Julian  format. 


Figure  18.  The  Velocity  Profile  Viewer  showing  the  proportions  of  lines  and  text  when  using  a  large-sized  window 
and  wide  line  weight. 

The  window  size  is  1599  x  1161  pixels.  The  lines  are  4  pixels  wide  for  small  text  and  thin  lines  and  5  pixels  wide  for 
large  text  and  wide  lines. 


Mouse  and  Keyboard  Control 


21 


Figure  19.  The  Velocity  Profile  Viewer  showing  the  proportions  of  lines  and  text  when  using  a 
medium-sized  window  and  wide  line  weight. 

The  window  size  is  893  x  640  pixels.  The  lines  are  4  pixels  wide  for  small  text  and  thin  lines  and  5 
pixels  wide  for  large  text  and  wide  lines. 


Figure  20.  The  Velocity  Profile  Viewer  showing  the  proportions  of  lines  and  text  when  using  a 
medium-sized  window  and  medium  line  weight. 

The  window  size  is  893  x  640  pixels.  The  lines  are  2  pixels  wide  for  small  text  and  thin  lines  and  3 
pixels  wide  for  large  text  and  wide  lines. 
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Figure  21.  The  Velocity  Profile  Viewer  showing  the  proportions  of  lines  and  text  when  using  a 
medium-sized  window  and  narrow  line  weight. 

The  window  size  is  893  x  640  pixels.  The  lines  are  1  pixel  wide  for  all  text  and  lines. 
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Figure  22.  The  Velocity  Profile  Viewer  showing  the  proportions  of  lines  and  text  when  using  a  small¬ 
sized  window  and  narrow  line  weight. 

The  window  size  is  415  x  305  pixels.  The  lines  are  1  pixel  wide  for  all  text  and  lines. 
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Figure  23.  Details  of  a  portion  of  the  Date  label  and  Main  Graph  in  the  Velocity  Profile  Viewer  with  dif¬ 
ferent  line  thicknesses  and  antialiasing  settings. 

(A)  thick  lines  and  text  without  antialiasing;  (B)  thin  lines  and  text  without  anitaliasing;  (C)  thick  lines  and 
text  with  antialiasing;  and  (D)thin  lines  and  text  with  antialiasing. 
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Figure  24.  Details  of  a  portion  of  the  three-dimensional  velocity  profile  in  the  Velocity  Profile 
Viewer  including  arrows,  grid  lines,  and  axis  labels  with  different  line  thicknesses  and  antialias¬ 
ing  settings. 

(A)  thick  lines  and  text  without  antialiasing;  (B)  thick  lines  and  text  with  antialiasing;  (C)  thin  lines 
and  text  without  antialiasing;  and  (D)  thin  lines  and  text  with  antialiasing. 
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Axis  Commands 

Axis  commands  change  the  limits  of  the  U  and  V  axes 
that  are  shown  at  the  base  of  the  3D  profile.  These  commands 
can  be  useful  when  comparing  profiles  from  different  files  that 
may  have  differing  default  axis  scales.  As  with  the  bin  graphs, 
the  axis  limits  and  grid  increments  are  rounded  to  the  nearest 
5,  10,  25,  or  to  one  of  these  numbers  multiplied  by  a  power 
of  10.  The  axis  scaling  commands  use  a  multiplier  to  increase 
or  decrease  the  axis  span.  Therefore,  the  commands  some¬ 
times  should  be  repeated  to  modify  the  axes  limits  enough  to 
be  bumped  to  the  next  grid  increment.  Table  4  describes  the 
commands  on  the  Axis  menu.  Figure  25  shows  the  effects  of 
axis  movement  commands.  In  each  snapshot,  the  U  and  V 
axes  span  200  units.  The  span  of  each  axis  is  shifted  individu¬ 
ally  between  ranges  of  -125  to  75,  -100  to  100,  and  -75  to 
125.  The  velocity  profile  remains  in  the  same  location  within 
the  window  while  the  grid  and  axes  are  displaced  on  eight  of 
the  nine  combinations  shown  in  figure  25.  Figure  26  shows 
the  effects  of  axis-scaling  commands  in  the  3D  profile  view. 


The  span  of  the  U  and  V  axes  are  scaled  individually  between 
ranges  of  -50  to  50,  -100  to  100,  and  -150  to  150.  For  each  of 
the  nine  combinations  shown  in  figure  26,  the  velocity  profile 
remains  in  the  same  location  within  the  window  while  the  grid 
and  axes  change  size.  When  both  axes  are  small,  the  velocity 
profile  is  short  with  very  little  spacing  between  arrows  (fig. 
26A).  If  at  least  one  axis  has  a  larger  span,  the  height  of  the 
profile  increases  (fig.  26B-I). 

Table  4.  Commands  on  the  Axis  menu  of  the  Velocity  Profile 
Viewer. 


[These  commands  affect  the  base  of  the  three-dimensional  profile.  See  figures 
25-26  for  examples] 


Command  Key 

Command  Description 

6 

Decreases  the  span  of  the  U  axis. 

7 

Increases  the  span  of  the  U  axis. 

8 

Decreases  the  span  of  the  V  axis. 

9 

Increases  the  span  of  the  V  axis. 

Shift+6 

Shifts  the  span  of  the  U  axis  lower. 

Shift+7 

Shifts  the  span  of  the  U  axis  higher. 

Shift+8 

Shifts  the  span  of  the  V  axis  lower. 

Shift+9 

Shifts  the  span  of  the  V  axis  higher. 
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Figure  25.  Screen  captures  showing  the  effects  of  shifting  the  span  of  the  U  and  V  axes  in  the  Three-Dimensional 
Profile  View  of  the  Velocity  Profile  Viewer. 


(F)  straight  right,  (G)  down  and  to  the  left,  (FI)  straight  down,  and  (I)  down  and  to  the  right. 
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Figure  26.  Screen  captures  showing  the  effects  of  axis-scaling  commands  in  the  Three-Dimensional  Profile  View  of  the 
Velocity  Profile  Viewer. 

The  axis  spans,  in  units,  for  the  U  and  V  axes,  respecively,  are  (A)  100  x  100;  (B)  200  x  100;  (C)  300  x  100;  (D)  100  x  200;  (E) 
200  x  200;  (F)  300  x  200;  (G)  100  x  300;  (H)  200  x  300;  and  (I)  300  x  300. 
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Time-Series  Commands 

Time-series  commands  affect  the  Main  Graph  near  the 
top  of  the  VPV  window  (fig.  27).  A  vertical  red  line  shows 
where  the  present  date  and  time  falls  on  each  graph.  By 
default,  the  bin-averaged  U  velocity  and  water-level  curves  are 
overlaid  using  separate  vertical  scales.  A  mean  value  for  each 
velocity  and  water  level  is  plotted  as  a  dotted  line  in  the  same 
color  as  its  respective  time  series.  If  water-level  values  are  not 
included  in  the  data  file,  the  water-level  curve  is  omitted.  If 
both  time  series  are  disabled,  the  Main  Graph  is  hidden.  Axis 
labels  are  shown  or  hidden  with  other  secondary  information 
(command  “2”,  table  3). 

The  bin-averaged  U  velocity  is  the  average  U  velocity 
component  value  for  all  bins  with  nonzero  values.  This  keeps 
missing  data,  which  are  stored  as  zeros,  from  affecting  the 
average.  Changing  the  principal  direction  causes  the  U  compo¬ 
nents  to  change,  which  will  be  reflected  in  the  Bin-Averaged 
U  plot. 

By  default,  gaps  in  the  data  time  series  are  made  more 
obvious  by  displaying  gap  indicators,  which  are  blue  verti¬ 
cal  lines  shown  at  the  beginning  and  end  of  each  gap  in  the 
Bin-Averaged  U  plot  (fig.  28).  When  the  beginning  and  end 


of  a  data  gap  are  visible  in  a  graph,  a  blue  line  connects  the 
last  point  before  the  gap  to  the  first  point  after  the  gap.  Table  5 
describes  the  commands  on  the  Time  Series  menu  that  are  to 
be  used  with  the  Bin- Averaged  U  plot  in  the  Main  Graph. 


Table  5.  Commands  on  the  Time  Series  menu  of  the  Velocity 
Profile  Viewer. 


[See  figures  27-28  for  examples] 


Command  Key 

Command  Description 

Q 

Shows  Bin- Averaged  U  in  the  Main  Graph 
above  the  profile. 

w 

Shows  Water  Level  in  the  Main  Graph 
above  the  profile,  if  the  data  were  given 
in  the  input  file. 

[  (left  square  bracket) 

Shows  a  shorter,  more  detailed  span  of  the 
time  series. 

]  (right  square  bracket) 

Shows  a  longer  span  of  the  series. 

Shift-G 

Shows  vertical  lines  to  indicate  periods  of 
missing  data. 

Figure  27.  The  Main  Graph  of  the  Velocity  Profile  Viewer  showing  variations  in  plots  of  water  level  and  bin-averaged  U 
velocity. 

(A)  only  water  level  with  a  short  time  span  showing  a  high  level  of  detail;  (B)  water  level  and  bin-averaged  U  velocity  with 
a  medium  time  span  showing  a  medium  level  of  detail;  and  (C),  only  bin-averaged  U  velocity  with  a  long  time  span  show¬ 
ing  a  low  level  of  detail. 
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Short  Gaps  Long  Gap 


Figure  28.  The  Main  Graph  of  the  Velocity  Profile  Viewer  showing  markers  for  short  and  long  gaps  in  a  data  series. 
Short  gaps  appear  as  light  blue  vertical  lines.  The  colors  of  the  marker  lines  fade  from  light  blue  at  the  start  of  a  long 
gap  to  medium  blue  at  the  end. 


Orientation  Commands 

VPV  is  capable  of  viewing  a  profile  from  any  orientation 
by  using  the  mouse  to  rotate  the  entire  grid.  But  with  respect 
to  the  grid,  it  also  is  possible  to  reorient  the  profile  so  that  the 
primary  flow  direction  is  along  the  U  axis.  This  reorientation 
is  done  by  redefining  the  principal  direction. 

The  principal  direction  represents  the  primary  direction 
of  positive  flow  and  is  measured  clockwise  from  the  top  of  the 
grid.  By  default,  the  principal  direction  is  90  degrees,  which 
causes  the  U  axis  to  represent  east  velocity  and  the  V  axis  to 
represent  north  velocity,  assuming  the  first  column  in  the  input 
file  is  the  east  component  and  the  second  column  is  the  north 
component.  For  a  channel  with  a  positive  U  component  that 
flows  east,  the  default  grid  allows  the  user  to  view  the  profile 
from  the  south  bank  looking  north  across  the  channel. 

Table  6  describes  the  commands  on  the  Orientation  menu. 
If  the  principal  direction  of  the  profile  is  known,  the  user  can 
rotate  the  axes  and  view  the  profile  perpendicularly  to  that 
direction.  The  Bin- Averaged  U  plot  also  will  be  recalculated 
and  the  grid  will  be  resized  to  accommodate  the  new  shape  of 
the  plot. 

If  the  user  doesn’t  know  the  principal  direction  angle,  it 
can  be  estimated  by  using  the  commands  “<“  and  “>”.  Using 
one  of  these  keys  will  overlay  white  axes  on  the  profile  base  as 
a  preview  of  how  the  new  axes  would  line  up  with  the  velocity 
profile.  The  user  should  continue  to  rotate  the  axes  until  they 
are  aligned  with  the  velocity  profile.  Once  editing  of  the  angle 
begins,  the  principal  direction  label  shows  the  actual  default 
of  “90.0”  rather  than  “None.”  Figures  29-31  show  a  velocity 
profile  before,  during,  and  after  a  realignment  of  the  principal 
direction,  respectively. 


Table  6.  Commands  on  the  Orientation  menu  of  the  Velocity  Pro¬ 
file  Viewer. 


[See  figures  29-32  for  examples] 


Command  Key 

Command  Description 

.  (period) 

Increases  the  principal  direction  indicators  by 
5.0  degrees. 

> 

Increases  the  principal  direction  indicators  by 
0.1  degree. 

,  (comma) 

Decreases  the  principal  direction  indicators  by 
5.0  degrees. 

< 

Decreases  the  principal  direction  indicators  by 
0.1  degree. 

Shift-P 

Recalculates  the  U  and  V  components  of  the 
velocity  profile  bins  using  the  newly  chosen 
principal  direction. 

P 

Switches  between  viewing  the  profile  in  the 
principal  direction  and  viewing  it  in  its  origi¬ 
nal  orientation. 

While  setting  the  principal  direction,  a  preview  of  the 
new  angle  overlays  the  profile  base  as  a  multi-colored,  pie¬ 
shaped  portion  of  a  unit  circle  that  increases  from  a  sliver 
when  the  angle  is  near  0  degrees  up  to  a  full  circle  when  the 
angle  is  near  360  degrees.  The  angle  is  clamped  to  the  range 
-360  to  360  degrees.  Figure  32  shows  a  detail  of  the  graphic 
representation  of  the  angle  being  selected  as  the  new  principal 
direction. 
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Figure  29.  The  Velocity  Profile  Viewer  before  a  realignment  of  the  profile's  principal  direction  with  the  U  axis. 
The  principal  direction  label  shows  the  default  value  of  "None." 
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Figure  30.  The  Velocity  Profile  Viewer  during  a  realignment  of  the  profile's  principal  direction  with  the  U  axis. 

The  new  alignment  of  the  axes  and  the  graphic  representation  of  the  new  angle  are  superimposed  on  the  grid.  The 
specified  angle  is  shown  in  white  nearthe  bottom  right  corner  of  the  window.  The  principal  direciton  label  shows 
"90.0." 
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Figure  31.  The  Velocity  Profile  Viewer  after  a  realignment  of  the  profile's  principal  direction  with  the  U  axis. 
The  principal  direction  label  has  changed  to  "55.0."  The  grid  and  axis  limits  are  rescaled  to  fit  the  new  U  and  V 
bounds  of  the  profile. 
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Figure  32.  A  detail  of  the  graphic  representation  of  the  angle  being  selected  as  the  new  principal  direction. 
The  two  white  arrows  represent  how  the  U  and  V  axes  would  lineup  below  the  profile. 


Animation  Commands 

Animation  commands  affect  how  the  time  series  “plays”. 
The  frame  rate  can  be  increased,  decreased,  stopped,  or 
reversed.  There  are  several  frame  rates  between  0  and  1  that  let 
the  file  play  forward  more  slowly  if  the  speed  of  the  computer 
causes  the  frame  rate  to  be  too  high.  Table  7  describes  the 
commands  on  the  Animation  menu. 

The  “Y”  command  changes  the  way  frame  rates  between 
0  and  1  are  shown.  The  default  is  to  interpolate  from  one  time 
step  to  the  next.  This  looks  smooth,  but  the  majority  of  frames 
shown  are  fictitious,  (for  example,  49  interpolations  and  1 
actual).  The  other  method  repeatedly  shows  the  same  frame 
and  then  moves  to  the  next  (50  actual,  50  actual,  and  so  on). 
The  latter  method  is  sometimes  desirable  if  the  user  wants 
to  view  only  actual  data  from  the  file.  Figure  33  shows  how 
the  Time  Step  Increment  label  displays  various  increments. 
Usually,  the  time  step  advances  too  quickly  to  read  the  number 
of  each  interpolated  time  step,  but  the  user  can  see  it  advanc¬ 
ing.  The  interpolated  time  step  is  shown  as  a  reminder  that  the 
frames  are  interpolated. 


Table  7.  Commands  on  the  Animation  menu  of  the  Velocity  Profile 
Viewer. 


[See  figure  33  for  example] 


Command  Key 

Command  Description 

N 

Stops  animation  on  the  most  recently  shown 
time  step.  Acts  as  a  toggle  to  start  animation  if 
stopped. 

+ (plus) 

or 

Increases  the  frame  rate. 

=  (equal) 

-  (minus) 

Decreases  the  frame  rate. 

Y 

Interpolates  between  time  steps  when  the  increment 
is  between  zero  and  one.  Acts  as  a  toggle  to  draw 
only  exact  time  steps  if  interpolation  is  on. 

34 
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Figure  33.  Screen  captures  of  the  Time  Step  Increment  label  at  various  rates. 
(B)  through  (H)  show  the  rate  that  results  from  giving  the  command  for  the 
previous  rate. 


Figure  33 A  shows  a  rate  of  2.  Figures  JJB-H  show  the 
rate  that  results  from  decreasing  the  rate  above  it.  Figures 
33 C-G  are  fractional  forward  rates,  with  1/100  being  the  slow¬ 
est.  The  fractional  rates  tell  which  interpolated  frame  currently 
is  being  shown.  For  example,  in  figure  35F,  the  rate  is  1/50  and 
the  displayed  profile  is  the  29th  of  50  interpolations  between 
the  displayed  time  step  and  the  next  time  step.  Figure  55H  is  a 
negative  rate  that  causes  the  animation  to  play  backwards.  In 
figures  JJI-J,  the  asterisk  indicates  that  the  viewer  is  stopped 
on  one  time  step.  Figure  331  shows  a  fractional  rate  of  1/20,  so 
when  it  is  stopped,  it  shows  the  interpolation  progress  toward 
the  next  frame  as  0  of  20  frames. 


Bin  Graphs  Commands 

Bin  Graphs  commands  affect  the  profile  when  it  is  shown 
as  four  time-series  graphs  in  place  of  the  3D  profile.  The  “[” 
and  “]”  keyboard  commands  ( table  5)  show  either  a  shorter 
or  longer  span  of  the  time  series,  respectively.  Most  Orienta¬ 
tion,  Animation,  and  Jump  commands  also  work  with  the 
bin  graphs.  See  the  Zoom  Commands  and  View  Commands 
sections  of  this  report  for  explanations  of  using  the  I,  Shift+I, 
O,  and  Shift+O  commands  ( table  2)  or  the  R  and  C  commands 
( table  3)  in  the  Bin  Graph  View. 
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Table  8  describes  the  commands  on  the  Bin  Graphs  menu. 
Figures  34-38  show  different  displays  for  the  Bin  Graph  View. 
The  Main  Graph  is  at  the  top  of  the  window  showing  bin-aver¬ 
aged  U  velocity,  except  in  figure  35  where  it  was  turned  off 
using  the  “Q”  and  “W”  commands  ( table  5).  The  date,  time, 
and  location  labels  are  shown  at  the  top  of  the  window  in 
each  figure,  except  figure  34  where  they  were  turned  off  using 
the  “1”  command  ( table  3).  Principal  direction  and  time  step 
labels  are  hidden  in  figures  34-38,  except  in  figure  35,  where 
they  were  turned  on  using  the  “2”  and  “3”  commands  (table 
3).  The  axis  labels  and  titles  are  shown  beside  each  graph  in 
figures  34-38,  except  in  figure  36  where  they  were  turned  off 
using  the  “4”  command  ( table  3).  The  “C”  command  is  used 
to  show  the  colored  backgrounds  in  figures  35-38. 


Table  8.  Commands  on  the  Bin  Graphs  menu  of  the  Velocity  Pro¬ 
file  Viewer. 


[See  figures  34-38  for  examples] 


Command  Key 

Command  Description 

M 

Toggles  between  the  three-dimensional  Profile  View 
and  the  Bin  Graph  View. 

K 

In  Bin  Graph  View,  toggles  between  showing  U  and 

V  component  curves  and  angled  sticks. 

Z 

Shows  the  previous  bin  in  the  graph  beneath  the  cur¬ 
sor.  If  the  lowest-number  bin  is  showing,  it  cycles 
to  the  highest-number  bin. 

X 

Shows  the  following  bin  in  the  graph  beneath  the 
cursor.  If  the  highest-number  bin  is  showing,  it 
cycles  to  the  lowest-number  bin. 

Figure  34.  The  Bin  Graph  View  of  the  Velocity  Profile  Viewer  showing  U  and  V  component  graphs  on  a  black 
background  with  no  lines  of  text  displayed. 

Graphs  for  bins  1, 8, 15,  and  23  are  shown  below  the  Main  Graph.  The  time  span  is  shortened  to  show  less 
than  one  tidal  cycle  to  see  more  detail  on  the  curves. 
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Figure  35.  The  Bin  Graph  View  of  the  Velocity  Profile  Viewer  showing  U  and  V  component  graphs  on  a  blue  background 
with  all  lines  of  text  displayed  in  yellow. 

The  Main  Graph  is  hidden  (using  the  "Q"  and  "W"  commands),  but  graphs  for  bins  17-20  are  shown.  The  time  span  shows 
about  8  tidal  cycles. 
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Figure  36.  The  Bin  Graph  View  of  the  Velocity  Profile  Viewer  showing  tidal  velocity  stick  plots  on  a  blue  background. 
Graphs  for  bins  17-20  are  shown  below  the  Main  Graph.  The  time  span  shows  about  1.5  tidal  cycles. 
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Figure  37.  The  Bin  Graph  View  of  the  Velocity  Profile  Viewer  showing  tidally  filtered  velocity  stick  plots  on  a  blue  back¬ 
ground. 

Graphs  for  bins  1, 7, 13,  and  19  are  shown  below  the  Main  Graph. 
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Figure  38.  The  Bin  Graph  View  of  the  Velocity  Profile  Viewer  showing  vertically  shifted  and  rescaled  stick  plots. 

This  shows  the  same  time  span  and  data  as  shown  in  Figure  37  of  this  report,  except  that  the  bins  showing  are  13, 
15, 17,  and  19.  The  stick  plot  axis  spans  all  have  been  decreased  and  shifted  from  between  -40  and  10  in  Figure  41  to 
between  -25  and  5  in  this  figure.  The  Main  Graph  Y  axis  also  is  affected. 


Help  Commands 

Help  commands  display  information  about  VPV  and 
using  the  mouse.  The  graphics  libraries  that  VPV  uses  make  it 
difficult  to  implement  a  sophisticated  help  system  with  popup 
windows,  so  the  Help  screen  was  added  as  a  convenience  to 
make  basic  information  available  to  the  user  at  run  time  with¬ 
out  having  to  refer  to  the  manual.  By  using  these  commands 


and  the  popup  menu,  users  who  are  familiar  with  the  applica¬ 
tion  should  be  able  to  refresh  their  memories  on  the  mouse 
controls.  However,  the  VPV  manual  should  be  consulted  for 
detailed  instruction. 

If  antialiasing  is  turned  on,  the  help  screen  will  have  a 
slightly  different  appearance.  Table  9  describes  the  commands 
on  the  Help  menu.  Figure  39  shows  help,  version,  and  author 
information  within  the  VPV  window. 
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Table  9.  Commands  on  the  Help  menu  of  the  Velocity  Profile 
Viewer. 


[See  figure  39  for  example] 


Command  Key 

Command  Description 

Shift-M 

Displays  a  short  description  of  what  clicking  and 
dragging  the  mouse  does  when  various  meta 
keys  are  held  down.  Covers  the  center  area  of 
the  window  where  the  three-dimensional  profile 
would  be  drawn. 

V 

Displays  version  and  author  information  along  the 
bottom  of  the  window  and  a  small  Velocity  Profile 
Viewer  logo  near  the  top  of  the  window. 

Main  Menu  Commands 

There  are  two  commands  at  the  bottom  of  the  main  menu, 
below  the  submenus  ( table  10).  See  the  Printing  section  of  this 
report  for  further  information  regarding  the  Shift+S  command. 


i  ues  spinning  after  mouse  button  is  released 
nslation  of  profile  in  3D;  of  axis  in  2D 
;t  time  step  in  any  mode 


Figure  39.  The  Velocity  Profile  Viewer  after  giving  the  "Mouse  Help"  and  "About  VPV"  commands. 

The  "About  VPV"  command  shows  (A)  the  VPV  logo  at  the  top  and  four  lines  of  text  at  the  bottom.  The  text 
includes  the  name  of  the  program,  date  of  the  last  revision,  author,  and  agency  information.  The  "Mouse 
Help"  command  covers  the  center  area  (B)  with  lines  of  text. 
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Table  10.  Commands  on  the  Main  menu  of  the  Velocity  Profile 


Viewer. 

[See  figures  40-42  for  examples] 

Command  Key 

Command  Description 

Shift-S 

Saves  a  four-view  representation  of  the  current  time 
step  to  a  PostScript  file. 

Escape 

Exits  the  program,  closing  the  Velocity  Profile 

Viewer  window  immediately. 

Printing 

VPV  has  the  capability  of  creating  printable  output.  The 
Shift+S  command  ( table  10)  creates  a  printable  PostScript 
file  in  the  same  directory  as  the  input  file,  with  care  taken 
not  to  overwrite  any  existing  file.  The  first  file  name  it  tries 
is  “vpv01.ps”.  If  that  file  exists,  it  tries  “vpv02.ps”  and  so 
on  until  it  finds  an  unused  filename.  If  “vpv01.ps”  through 
“vpv99.ps”  all  exist,  then  the  output  overwrites  the  file 
“vpv.ps”. 

The  file  can  be  printed  on  a  PostScript  printer  or  viewed 
and  printed  on  any  printer  using  a  PostScript  viewer  applica¬ 
tion  such  as  Ghostview  or  GSview,  which  are  available  at 
http://www.cs.wisc.edu/~ghost/.  The  file  also  can  be  imported 
into  an  illustration  package  such  as  Adobe  Illustrator  or  Corel 
Draw,  and  manipulated  as  vector  graphics. 


The  output  is  an  8.5  x  1 1-inch  print,  separated  into  four 
different  views  of  a  profile  (fig.  40).  The  primary  and  second¬ 
ary  information  from  the  screen  is  shown  above  the  quadrants. 
The  top  right  view  (fig.  40B)  is  a  perspective  of  the  profile 
matching  the  image  on  the  screen.  The  other  three  views  make 
up  a  standard  three-view,  orthographic  projection  of  the  top 
(U-V)  (fig .  40A),  side  (U-Z)  (fig.  40C),  and  front  (V-Z)  (fig. 
40X0)  of  the  profile. 

The  output  matches  the  screen  as  closely  as  possible. 
Some  colors  are  modified  so  they  will  be  visible  on  white 
paper.  The  perspective  view  uses  the  same  rotation  and  zoom 
as  is  on  the  screen.  It  closely  matches  the  image  on  the  screen 
in  the  area  below  the  Main  Graph,  but  does  not  include  the 
axis  labels.  The  perspective  view  always  shows  a  projection 
on  the  base,  even  if  “Color  by  depth”  is  not  selected.  The  same 
output  is  created,  regardless  of  whether  the  3D  Profile  View 
or  Bin  Graphs  View  is  being  shown  on  the  screen  while  the 
command  is  given. 

When  “Color  by  depth”  is  selected,  the  PostScript  output 
is  color  (fig.  41),  and  when  it  is  deselected,  the  output  is  black 
and  white  (fig.  40).  The  View  commands  that  affect  the  output 
file  are  “S”,  “A”,  “C”,  “1”,  “2”,  “4”,  “G”,  and  “J”  (table  3,  fig. 
42). 


The  Axis  commands  can  be  used  to  change  the  axis  lim¬ 
its.  The  orthographic  views  will  scale  the  axes  to  fit  each  quad¬ 
rant  of  the  page.  Each  quadrant  has  a  clipping  region  outline  to 
keep  one  view  from  showing  on  top  of  another. 
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Figure  40.  Example  showing  black  and  white  PostScript  output  from  the  Velocity  Profile  Viewer. 

The  four  views  shown  are  (A)  top;  (B)  perspective;  (C)  front;  and  (0)  side.  Arrows,  the  profile  surface,  grid  lines,  axis  labels,  and  two 
lines  of  text  are  shown. 
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Figure  41.  Example  showing  color  PostScript  output  from  the  Velocity  Profile  Viewer  showing  a  profile  with  arrows,  a  surface,  and 
grid  lines  on  the  base. 

The  four  views  shown  are  (A)  top;  ( B )  perspective;  (C)  front;  and  (0)  side.  Arrows,  the  profile  surface,  grid  lines,  axis  labels,  and  the 
date  and  location  text  are  shown.  The  units  and  principal  direction  text  are  not  shown. 
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Figure  42.  Example  showing  color  PostScript  output  from  the  Velocity  Profile  Viewer  showing  a  "bare"  profile. 

The  four  views  shown  are  (A)  top;  ( B )  perspective;  (C)  front;  and  (D)  side.  Arrows,  axis  labels,  and  the  date  and  location  text  are 
shown.  The  profile  surface,  grid  lines,  and  the  units  and  principal  direction  text  are  not  shown. 
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APPENDIXES 


Appendix  1:  Installing  and  Running  the 
Velocity  Profile  Viewer  Application 

VPV  is  available  on  the  World  Wide  Web  at  http:// 
ca.water.usgs.gov/program/sfbay/vpv/.  This  report  describes 
the  version  of  VPV  last  modified  on  August  15,  2004. 

VPV  is  a  simple  application  that  consists  only  of  an 
executable  file,  although  it  requires  the  availability  of  support¬ 
ing  libraries. 

Installing  the  Application 

To  install  VPV  on  a  personal  computer  (PC)  running 
Windows,  download  the  vpv.exe  and  vpv.ico  files  from  the 
VPV  web  page  to  any  directory  on  the  PC.  A  shortcut  to  the 
application  can  be  created  and  placed  on  the  Windows  desktop, 
and  the  vpv.ico  file  can  be  set  as  the  icon  for  this  shortcut  (fig. 
Al).  Four  Dynamic  Link  Library  (DLL)  files  also  are  required: 
msvcrt.dll,  opengl32.dll,  glu32.dll,  and  glut32.dll.  These  files 
are  available  on  the  VPV  website.  The  files  should  be  included 
with  post- 1997  versions  of  Windows  with  the  exception  of 
glut32.dll,  which  usually  does  not  come  with  Windows.  If  any 
of  the  four  required  DLL  files  are  not  in  the  Windows  path, 
VPV  will  show  an  error  at  run  time.  Download  any  missing 
DLL  files  from  the  VPV  web  page  and  place  them  in  the  Win¬ 
dows  System  directory,  or  in  the  same  directory  as  the  VPV 
executable  file. 

To  install  VPV  on  an  SGI,  the  machine  must  be  running 
under  IRIX  5.3  or  later,  and  have  OpenGL  1 .0  and  GLUT  3.6 
installed.  These  applications  can  be  downloaded  from  http:// 
www.opengl.org.  The  vpv  executable  file  can  be  downloaded 
to  any  directory  in  the  path. 


Figure  Al.  The  Velocity  Profile  Viewer  icon  as  it  appears  on  the 
Windows  desktop. 


Running  the  Application 

To  test  the  installation,  run  the  application  by  typing 
“vpv”  (lowercase)  or  double-clicking  on  the  application  in  a 
folder  window.  A  window  should  appear  with  the  VPV  logo 
and  an  error  stating  that  the  data  file  was  unspecified  (fig .  A2 ), 
which  indicates  that  all  required  application  files  were  found. 
Close  the  window  and  restart  VPV  with  a  data  file  argument  as 
described  in  the  Viewing  Data  section  of  this  appendix. 

If  an  error  appears  onscreen  that  says  a  DLL  could  not 
be  found  or  if  the  VPV  window  does  not  appear,  search  the 
system  for  the  required  DLL  files.  Windows  should  be  in  at 
least  16-bit  color  mode  for  VPV  to  display  correctly.  Note  that 
the  actual  colors  that  appear  onscreen  may  vary  depending  on 
the  settings  for  the  monitor,  display  driver,  or  operating  system 
color  mode. 

Viewing  Data 

To  open  a  data  file,  type  “vpv  (filename)”  in  a  command 
window,  or  drag  the  input  file  and  drop  it  on  the  executable 
file.  A  sample  data  file,  called  sample. vel,  is  available  on  the 
VPV  web  site. 
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To  open  data  that  are  stored  from  top  to  bottom,  as  is 
common  for  downward-looking  profiles,  use  the  “-downward” 
option  on  the  command  line,  which  simply  shows  the  bins  in 
reverse  order.  This  option  can  be  shortened  to  “-down”  or  “-d”. 

If  an  error  occurs  when  the  application  is  initialized  or 
loading  data,  processing  aborts  and  an  error  message  is  dis¬ 
played  in  the  window  (fig.  A2 )  until  the  application  is  closed. 
Table  A1  lists  all  the  possible  error  messages  displayed  by 
VPV  and  their  respective  causes. 

The  interior  dimensions  of  the  VPV  window  are  600  x 
600  pixels  when  it  first  appears  onscreen.  The  window  also 
shows  the  VPV  logo  and  identifies  the  author,  organization, 
and  the  revision  of  the  application.  VPV  reads  the  header  of 


the  data  file  to  determine  the  number  of  time  steps  in  the  file 
and  then  allocates  the  appropriate  amount  of  memory  to  store 
the  data.  As  each  data  time  step  is  read,  a  progress  meter  in  the 
window  displays  the  amount  of  allocated  space  that  has  been 
filled  fg.  A3).  For  small  data  sets,  the  progress  meter  may  be 
displayed  only  for  an  instant. 

If  either  velocity  component  of  a  bin  at  a  particular  time 
step  is  less  than  -999  or  greater  than  999,  the  data  for  that  bin 
are  interpreted  as  missing  and  both  components  are  stored  as 
zeros.  VPV  works  with  filtered  and  unfiltered  data  and  data 
files  with  or  without  water-level  data.  See  appendix  2  of  this 
report  for  more  information  regarding  data  input. 


USGS  Velocity  Profile  Viewer 


 |n|  x 


Figure  A2.  The  Velocity  Profile  Viewer  window  displaying  an  error  message  that  the  data  file  was  unspecified. 
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Loading  File... 


77%  Complete 


Figure  A3.  The  Velocity  Profile  Viewer  window  displaying  a  progress  meter  onscreen  while  loading  a  data  file. 
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Table  A1.  Error  messages  and  their  causes  displayed  by  the  Velocity  Profile  Viewer. 


Error  Message 

Cause  of  Error 

Error  reading  location  at  line  1 

The  end  of  the  file  was  reached  before  the  end  of  the  first  line. 

Error  reading  header  at  line  3 

The  end  of  the  file  was  reached  before  the  end  of  the  third  line. 

Error  reading  header  at  line  4 

The  end  of  the  file  was  reached  before  the  end  of  the  fourth  line. 

Error  reading  header:  bad  start  date 

A  valid  start  date  could  not  be  computed,  probably  because  the  year,  month,  or  day  of  the  start  date 
were  out  of  range,  not  in  the  proper  columns,  or  missing  altogether. 

Error  reading  header:  bad  end  date 

A  valid  end  date  could  not  be  computed,  probably  because  the  year,  month,  or  day  of  the  end  date 
were  out  of  range,  not  in  the  proper  columns,  or  missing  altogether. 

Error  in  header:  check  start  and  end  dates 

The  span  from  start  date  to  end  date  was  less  than  zero  or  greater  than  5,000  days. 

Error  in  header:  check  bin  info 

(1)  The  number  of  bins,  computed  as  the  difference  between  the  first  and  last  bin  in  the  header,  is 
less  than  zero,  greater  than  1,000,  or  missing  altogether. 

(2)  The  time  step  increment  is  less  than  or  equal  to  zero  or  greater  than  100. 

Error  opening:  data  file  unspecified 

No  data  file  was  specified  as  an  argument,  either  on  the  command  line  or  by  dragging  it  onto  the 
application  (shown  in  fig.  AT). 

Error  opening:  data  file  filename 

The  file  named  “filename”  could  not  be  found  and  opened. 

Error:  no  time  series  data  were  read 

No  data  were  recognized  in  the  file  after  the  header. 

Error:  data  file  could  not  be  read 

There  was  an  error  reading  the  data  file  that  was  not  caught  and  handled  by  one  of  the  other  error 
messages. 
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Appendix  2:  Data  Format  Description 


The  main  file  format  used  by  VPV  consists  of  a  five-line  header  followed  by  multiple  records  describing  the  velocity  profile  at 
each  time  step.  The  following  is  a  short  file  listing  of  the  VPV  data  format,  with  only  the  first  two  time  steps  showing: 

. Line  1  (File  Header) 

. Line  2  (File  Header) 

. Line  3  (File  Header) 

23  0.16667  0.50000  Line  4  (File  Header) 

1  95  6  10  . Line  5  (File  Header) 

14.83  0  00  95  6  1  1150  . Line  6  (Time  Step  Header) 

5  0  -14.5  0  . Line  7  (Bin  1,  Time  Step  1) 

The  first  five  lines  of  the  file  contain  header  information. 
Only  the  first  40  columns  of  the  header  are  read.  Comments 
can  be  written  to  the  right  of  column  40.  The  data  for  each 
time  step  begin  at  line  six.  For  each  time  step,  there  is  one 
header  line,  which  includes  date  and  time,  followed  by  one 
line  for  each  bin.  Each  bin  must  have  a  line,  even  if  the  data 
are  missing. 


SAMPLE 

15219951621995 
38  3  1122  6  2 
1 

95  6 

0.00000 
1 


2 

3 

4 

5 

6 

7 

8 
9 

10 
11 
12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 
23 

0 . 16667 
1 
2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 
23 


-38  . 
-37  . 
-31  . 
-37  . 
-37  . 
-38  . 
-42  . 
-42  . 
-41  . 
-41  . 
-42  . 
-41  . 
-39  . 
-40  . 
-41  . 
-39  . 
-39  . 
-36  . 
-16  . 
9999  . 
9999  . 
9999  . 
9999  . 
14 
-25  . 
-25  . 
-25  . 
-29  . 
-29  . 
-29  . 
-30  . 
-33  . 
-34  . 
-33  . 
-33  . 
-32  . 
-33  . 
-33  . 
-32  . 
-33  . 
-36  . 
-36  . 
-32  . 
9999  . 
9999  . 
9999  . 
9999 


.  00 
.  50 
.80 
.  90 
.80 
.  70 
.  90 
.  00 
.  60 
.  50 
.  70 
.  90 
.  00 
.  10 
.  10 
.  00 
.  10 
.  80 
.  90 
.  99 
.  99 
.  99 
.  99 


-14 
-9 
-3 
-10 
-14 
-18 
-18 
-19 
-21 
-23 
-24 
-27 
-26 
-27 
-25 
-25 
-21 
-15 
-10 
9999 
9999 
9999 
9999 
83000 

-8 


50 

60 

00 

90 

80 

60 

60 

00 

70 

50 

40 

90 

60 

60 

00 

40 

60 

45 

99 

99 

99 

99 


-9 

-10 

-12 

-13 

-13 

-12 

-12 

-13 

-14 

-14 

-16 

-17 

-18 

-18 

-18 

-18 

-21 

-20 

9999 

9999 

9999 

9999 


95 
95 
.  50 
.  70 
.80 
.  10 
.  10 
.  60 
.30 
.  80 
.30 
.40 
.  00 
.  70 
.  60 
.  90 
.  10 
.20 
.20 
.  90 
.  05 
.  99 
.  99 
.  99 
.  99 
95 
.  90 
.20 
.  10 
.  70 
.  70 
.  60 
.  50 
.  00 
.  90 
.40 
.  50 
.  60 
.30 
.30 
.80 
.  00 
.40 
.  10 
.  10 
.  99 
.  99 
.  99 
.  99 


1  1167 


Header  Format 

Table  A2  describes  each  line  in  the  header.  The  first  line 
of  the  header  is  the  name  of  the  station  where  the  data  were 
collected,  and  must  be  between  0  and  40  characters  long.  Extra 
characters  at  the  end  of  the  line  are  ignored. 

VPV  skips  the  second  and  third  lines  and  doesn't  use  the 
provided  information.  The  two  lines  can  be  blank  or  they  can 
be  filled  in  as  described  below. 

The  second  line  is  a  14-digit  integer  that  tells  the  starting 
and  ending  date  of  the  record.  Digits  1-3  are  the  starting  Julian 
day,  digits  4-7  are  the  starting  year,  digits  8-10  are  the  ending 
Julian  day,  and  digits  11-14  are  the  ending  year. 

The  third  line  is  the  latitude  and  longitude  of  the  collec¬ 
tion  station. 

The  fourth  line  is  made  up  of  four  fields.  The  first  field  is 
an  integer  representing  the  lowermost  (first)  bin  in  the  vertical 
velocity  profile;  typically  1.  (The  bin-numbering  scheme  is 
assumed  to  start  at  the  bottom  and  work  upward  unless  the 
“-d”  option  is  given).  The  second  field  is  an  integer  represent¬ 
ing  the  number  of  the  last  bin,  which  can  be  as  large  as  30. 

The  third  field  is  a  decimal  number  representing  the  time  step 
increment,  in  hours.  A  30-minute  interval  would  be  recorded 
as  “0.5”.  The  fourth  field  is  a  decimal  number  representing  the 
bin  height.  This  field  is  ignored  by  VPV.  The  Fortran  format  to 
write  this  line  would  be  “15,  lx,  19,  6x,  F9.5,  lx,  F9.5”.  VPV 
is  written  in  the  C  programming  language,  however,  and  it 
reads  only  two  int  values  and  a  float  value  separated  by  spaces. 

The  fifth  line  has  six  fields,  all  integers.  They  are  the 
starting  year,  month,  and  day,  and  ending  year,  month,  and 
day.  The  Fortran  write  format  would  be  “3(lx,  14),  5x,  3(lx, 
14)”,  but  VPV  just  looks  for  six  int  values  separated  by  spaces. 
VPV  uses  these  dates  to  calculate  the  size  of  its  storage  array. 
The  application  will  give  an  error  regarding  Julian  start  or  end 
dates  if  any  of  these  fields  are  missing. 
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Table  A2.  D  escription  of  each  line  of  the  header  in  the  input  file 
for  the  Velocity  Profile  Viewer. 

[VPV,  Velocity  Profile  Viewer] 


Line  Number 

Location 

Description 

1 

Profile  identification 

Columns  1  -  40 

Name  of  the  station  where  the 
data  were  collected,  alpha-nu¬ 
meric  (40  characters). 

2 

Starting  and  ending  dates. 

Ignored  by  VPV. 

Columns  1  -  3 

Starting  Julian  day,  integer, 
includes  leading  zeros. 

Columns  4-7 

Starting  year,  integer. 

Columns  8-10 

Ending  Julian  day,  integer, 
includes  leading  zeros. 

Columns  11-14 

Ending  year,  integer. 

3 

Profile  geographic  location. 
Ignored  by  VPV. 

Columns  1  -  2 

Latitude  degrees,  integer. 

Columns  3-4 

Latitude  minutes,  integer. 

Columns  5-6 

Latitude  seconds,  integer. 

Columns  7  -  9 

Longitude  degrees,  integer. 

Columns  10-11 

Longitude  minutes,  integer. 

Columns  12-13 

Longitude  seconds,  integer. 

4 

Bin  information. 

Field  1,  Space 
Delimited 

Number  of  first  bin,  integer. 

Field  2,  Space 
Delimited 

Number  of  the  last  bin,  integer. 

Field  3,  Space 

Time  step  increment  in  hours. 

Delimited 

decimal  number. 

Field  4,  Space 

Bin  height,  decimal  number. 

Delimited 

Ignored  by  VPV. 

5 

Starting  and  ending  dates. 

Field  1,  Space 
Delimited 

Starting  year,  integer. 

Field  2,  Space 
Delimited 

Starting  month,  integer. 

Field  3,  Space 
Delimited 

Starting  day,  integer. 

Field  4,  Space 
Delimited 

Ending  year,  integer. 

Field  5,  Space 
Delimited 

Ending  month,  integer. 

Field  6,  Space 
Delimited 

Ending  day,  integer. 

Time-Step  Data  Format 

The  rest  of  the  data  file  consists  of  a  record  for  each  time 
step.  Each  record  has  a  single-line  header,  followed  by  a  line 
for  each  vertical  bin.  Table  A3  describes  the  header  and  data 
lines  for  a  time-step  record. 

The  time-step  header  line  has  six  fields.  The  first  two 
fields  are  decimal  numbers  and  the  last  four  fields  are  integers. 
The  first  field  is  the  time,  in  hours,  since  the  beginning  of  the 
file.  The  second  field  is  the  water  level.  If  water-level  data  are 
not  available,  the  value  of  the  field  should  be  zero.  The  last 
four  fields  are  the  year,  month,  day,  and  time  of  the  record. 

The  time  is  shown  as  a  decimal  representation  of  the  hour, 
multiplied  by  100.  For  example,  1 1:30  p.m.  would  be  “2350”. 
The  Fortran  write  format  for  the  line  would  be  “F10.5,  lx, 
F9.5,  4(lx,  14)”.  VPV  uses  a  pivot  year  of  60  for  all  two-digit 
years.  Therefore,  dates  are  assumed  to  be  between  the  years 
1960  and  2059  unless  they  are  entered  with  four-digit  years. 

The  lines  for  each  record  have  three  fields  each.  The  first 
field  is  the  bin  number,  starting  at  1 .  The  second  field  is  the 
U  component  of  the  velocity,  usually  east.  The  third  field  is 
the  V  component  of  velocity,  usually  north.  The  Fortran  write 
format  of  the  line  would  be  16,  2(lx,  F9.2).  If  the  data  for  a  bin 
are  missing  at  a  given  time  step,  the  U  and  V  values  should  be 
9999.99.  An  example  of  missing  data  is  shown  for  bins  20-23 
in  the  file  listing  at  the  beginning  of  appendix  2. 


Table  A3.  Description  of  the  header  and  data  line  of  a  timestep 
record  in  the  input  file  for  the  Velocity  Profile  Viewer. 


Line 

Field  Number, 
Spaced 
Delimited 

Description 

1 

Time  and  water  level. 

1 

Time  in  hours  since  the  beginning 
of  the  file,  decimal  number. 

2 

Water  level,  integer. 

3 

Year,  integer. 

4 

Month,  integer. 

5 

Day,  integer. 

6 

Time  as  decimal  hour  multiplied  by 
100,  integer. 

2  through 
(number  of 
bins  +  1) 

Bin  number  and  velocity 

1 

Bin  number  (1  to  number  of  bin), 
integer. 

2 

U  velocity  component,  decimal 
number. 

3 

V  velocity  component,  decimal 
number. 
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Appendix  3:  Legal  Notice 

VPV  is  free  software.  Permission  is  hereby  granted  to 
redistribute  and  use  the  software  as  long  as  the  USGS  is  given 
credit  for  being  the  original  creator  and  this  notice  accompa¬ 
nies  the  software.  Use,  modification,  and  redistribution  of  the 
source  code  is  allowed  under  the  terms  of  the  GNU  Lesser 
General  Public  License  (Free  Software  Foundation,  Inc., 
accessed  July  15,  2004),  wherever  it  applies  to  U.S.  Govern¬ 
ment  software. 

Every  effort  was  made  to  make  VPV  accurate  and  bug- 
free.  However,  the  software  is  provided  “AS  IS,”  without  a 
warranty  of  any  kind.  VPV  is  not  guaranteed  to  work  on  all 
data  files,  or  to  display  correct  results.  The  USGS  shall  not  be 
liable  for  any  damages  suffered  by  the  licensee  or  any  third 
party  as  a  result  of  using  or  distributing  the  software.  The 
USGS  makes  absolutely  no  claim  that  the  software  will  work 
as  described  in  the  accompanying  README  file,  and  is  not 
responsible  for  problems  caused  if  the  software  does  not  oper¬ 
ate  properly. 

User  Rights  Notice 

This  software  and  related  material  (data  and  (or)  docu¬ 
mentation),  contained  in  or  furnished  in  connection  with  VPV, 
are  made  available  by  the  U.S.  Geological  Survey  (USGS)  to 
be  used  in  the  public  interest  and  in  the  advancement  of  sci¬ 
ence.  You  may,  without  any  fee  or  cost,  use,  copy,  modify,  or 
distribute  this  software,  and  any  derivative  works  thereof,  and 
its  supporting  documentation,  subject  to  the  following  restric¬ 
tions  and  understandings. 

If  you  distribute  copies  or  modifications  of  the  software 
and  related  material,  make  sure  the  recipients  receive  a  copy 


of  this  notice  and  receive  or  can  get  a  copy  of  the  original  dis¬ 
tribution.  If  the  software  and  (or)  related  material  are  modified 
and  distributed,  it  must  be  made  clear  that  the  recipients  do  not 
have  the  original  and  they  must  be  informed  of  the  extent  of 
the  modifications.  For  example,  modified  files  must  include  a 
prominent  notice  stating  the  modifications  made,  the  author  of 
the  modifications,  and  the  date  the  modifications  were  made. 
This  restriction  is  necessary  to  guard  against  problems  intro¬ 
duced  in  the  software  by  others,  reflecting  negatively  on  the 
reputation  of  the  USGS. 

The  software  is  public  property  and  you  therefore  have 
the  right  to  the  source  code,  if  desired. 

You  may  charge  fees  for  distribution,  warranties,  and 
services  provided  in  connection  with  the  software  or  derivative 
works  thereof.  The  name  USGS  can  be  used  in  any  advertising 
or  publicity  to  endorse  or  promote  any  products  or  commer¬ 
cial  entity  using  this  software  if  specific  written  permission  is 
obtained  from  the  USGS. 

The  user  agrees  to  appropriately  acknowledge  the  authors 
and  the  USGS  in  publications  that  result  from  the  use  of  this 
software  or  in  products  that  include  this  software  in  whole  or 
in  part. 

Because  the  software  and  related  material  are  free  (other 
than  nominal  materials  and  handling  fees)  and  provided  “as 
is,”  the  authors,  the  USGS,  and  the  United  States  Government 
have  made  no  warranty,  express  or  implied,  as  to  accuracy  or 
completeness  and  are  not  obligated  to  provide  the  user  with 
any  support,  consulting,  training  or  assistance  of  any  kind  with 
regard  to  the  use,  operation,  and  performance  of  this  software 
nor  to  provide  the  user  with  any  updates,  revisions,  new  ver¬ 
sions,  or  “bug  fixes.” 

The  user  assumes  all  risk  for  any  damages  whatsoever 
resulting  from  loss  of  use,  data,  or  profits  arising  in  connection 
with  the  access,  use,  quality,  or  performance  of  this  software. 
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